Drop ANN exceptions from arrays and core/base.py #1568

loicdiridollou · 2025-12-18T19:07:32Z

Closes #xxxx (Replace xxxx with the Github issue number)
Tests added (Please use assert_type() to assert the type of any return value)
If I used AI to develop this pull request, I prompted it to follow AGENTS.md.

Quite a bit of clean up to comply with ANN rules.

Co-authored-by: Yi-Fan Wang <cmp0xff@users.noreply.github.com>

cmp0xff

Just reviewed a small portion of all changes.

cmp0xff · 2025-12-18T22:21:01Z

pandas-stubs/io/excel/_base.pyi

        storage_options: StorageOptions = ...,
        engine_kwargs: dict[str, Any] | None = ...,
    ) -> None: ...
-    def __fspath__(self): ...


I think this is functional: https://docs.python.org/3/library/os.html#os.PathLike.__fspath__

should return a string, according to the implementation

Since not documented, the question is do we need it, happy to revert and mark the return type as str, let me know your view

I guess it will be useful if ExcelFile is to be taken as a Path-like object. Would prefer to keep.

cmp0xff · 2025-12-18T22:24:11Z

pandas-stubs/core/arrays/timedeltas.pyi

-        skipna: bool = ...,
-    ): ...
-    def median(
+    def __init__(


I think __new__ is preferred over __init__. It is easier to understand the return types in __new__ than the typing hint of self in __init__.

Same as above

cmp0xff · 2025-12-18T22:25:42Z

pandas-stubs/core/arrays/timedeltas.pyi

+        freq: Frequency | None = None,
+        copy: bool = False,
+    ) -> None: ...
    __rmul__ = ...


This can also drop

Okay will drop, I wanted to keep it concise but happy to do more.

pandas-stubs/core/arrays/string_.pyi

cmp0xff · 2025-12-18T22:32:00Z

pandas-stubs/core/arrays/period.pyi

 class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps):
    __array_priority__: int = ...
-    def __init__(self, values, freq=..., dtype=..., copy: bool = ...) -> None: ...
+    def __init__(


__new__ instead of __init__?

cmp0xff · 2025-12-18T22:32:26Z

pandas-stubs/core/arrays/period.pyi

-    def __init__(self, values, freq=..., dtype=..., copy: bool = ...) -> None: ...
+    def __init__(
+        self,
+        values: Series[PeriodDtype] | npt.NDArray[np.integer] | PeriodIndex,


cmp0xff · 2025-12-18T22:35:08Z

pandas-stubs/core/arrays/sparse/array.pyi

    Ellipsis = "..."

 class SparseArray(ExtensionArray, ExtensionOpsMixin):
    def __init__(


__new__ instead of __init__?

Not sure it makes a difference here since we have only one value.

cmp0xff · 2025-12-18T22:35:57Z

pandas-stubs/core/arrays/sparse/array.pyi

+        sparse_index: SparseIndex | None = None,
+        fill_value: Scalar | None = None,
+        kind: str = "integer",
+        dtype: np.dtype | SparseDtype | None = ...,


Need to distinguish >= 3.11 (np.dtype) and 3.10 (np.dtype[Any])

cmp0xff · 2025-12-18T22:39:23Z

pandas-stubs/core/arrays/sparse/array.pyi

-    @property
-    def sp_index(self): ...
-    @property
-    def sp_values(self): ...
-    @property
-    def dtype(self): ...
-    @property
-    def fill_value(self): ...
-    @fill_value.setter
-    def fill_value(self, value) -> None: ...


I think removing them might not be a good idea. They seem to be the core use case of SpareArray. We can raise issues in Pandas for the proper documentation.

…1318_defaults_p2

pandas-stubs/core/arrays/masked.pyi

cmp0xff · 2025-12-19T16:52:50Z

pandas-stubs/core/arrays/integer.pyi

+    if sys.version_info >= (3, 11):
+        def __init__(
+            self, values: AnyArrayLike, mask: np_1darray, copy: bool = ...
+        ) -> None: ...
+    else:
+        def __init__(
+            self, values: AnyArrayLike, mask: np.ndarray, copy: bool = ...
+        ) -> None: ...


self, values: AnyArrayLike, mask: np_ndarray, copy: bool = ... would do in all cases

cmp0xff · 2025-12-19T17:21:59Z

pandas-stubs/core/arrays/datetimes.pyi

-    def month_name(self, locale=...): ...
-    def day_name(self, locale=...): ...
+    ) -> Self: ...
+    def to_pydatetime(self) -> npt.NDArray[np.object_]: ...


maybe np_1darray_object, also in other cases here

cmp0xff · 2025-12-19T17:22:20Z

pandas-stubs/core/arrays/datetimes.pyi

    is_year_end = ...
    is_leap_year = ...
-    def to_julian_date(self): ...
+    def to_julian_date(self) -> npt.NDArray[np.float64]: ...


maybe np_1darray_float

MarcoGorelli · 2025-12-22T10:28:58Z

should the title be updated to mention _excel/base.pyi rather than core/base.pyi?

MarcoGorelli · 2025-12-22T11:03:05Z

pandas-stubs/core/arrays/period.pyi

+    def __new__(
+        cls,
+        values: np_ndarray_anyint | PeriodArray | PeriodIndex | Series[Period],
+        freq: Frequency | None = None,


should this be PeriodFrequency?

MarcoGorelli

thanks for working on this!

some methods like isna are inherited from ExtensionArray, but could you elaborate on why the others are being removed? is it that they're not documented?

MarcoGorelli · 2025-12-22T11:27:26Z

pandas-stubs/core/arrays/boolean.pyi

-    def any(self, *, skipna: bool = ..., **kwargs: Any): ...
-    def all(self, *, skipna: bool = ..., **kwargs: Any): ...


sorry if i missed it but what happened to these?

any and all are undocumented, but personally I would prefer to keep them as well.

MarcoGorelli · 2025-12-22T11:51:01Z

pandas-stubs/core/arrays/sparse/array.pyi

-    def isna(self): ...
-    def shift(self, periods: int = 1, fill_value=...): ...
-    def unique(self): ...
-    def value_counts(self, dropna: bool = True): ...


why remove value_counts?

Agreed, maybe keeping it would be better

MarcoGorelli · 2025-12-22T11:54:21Z

pandas-stubs/core/arrays/sparse/array.pyi

        self, key: SequenceIndexer | tuple[int | ellipsis, ...]
    ) -> Self: ...
-    def copy(self): ...
-    def map(self, mapper): ...


why remove this?

Agreed, maybe keeping it would be better

cmp0xff · 2025-12-22T12:08:07Z

pandas-stubs/core/arrays/sparse/array.pyi

-    def isna(self): ...
-    def shift(self, periods: int = 1, fill_value=...): ...
-    def unique(self): ...
-    def value_counts(self, dropna: bool = True): ...


Agreed, maybe keeping it would be better

cmp0xff · 2025-12-22T12:08:24Z

pandas-stubs/core/arrays/sparse/array.pyi

        self, key: SequenceIndexer | tuple[int | ellipsis, ...]
    ) -> Self: ...
-    def copy(self): ...
-    def map(self, mapper): ...


Agreed, maybe keeping it would be better

cmp0xff · 2025-12-22T12:11:27Z

pandas-stubs/core/arrays/boolean.pyi

-    def any(self, *, skipna: bool = ..., **kwargs: Any): ...
-    def all(self, *, skipna: bool = ..., **kwargs: Any): ...


any and all are undocumented, but personally I would prefer to keep them as well.

cmp0xff · 2025-12-22T12:13:00Z

pandas-stubs/core/arrays/categorical.pyi

+    if sys.version_info >= (3, 11):
+        def argsort(
+            self, *, ascending: bool = ..., kind: str = ..., **kwargs: Any
+        ) -> npt.NDArray[np.intp]: ...


Probably just use one case and return

Suggested change

) -> npt.NDArray[np.intp]: ...

) -> np_ndarray_intp: ...

because the returned values seem to be indices, hence intp

cmp0xff · 2025-12-22T12:15:31Z

pandas-stubs/core/arrays/categorical.pyi

-    def __eq__(self, other) -> bool: ...
-    def __ne__(self, other) -> bool: ...
-    def __lt__(self, other) -> bool: ...
-    def __gt__(self, other) -> bool: ...
-    def __le__(self, other) -> bool: ...
-    def __ge__(self, other) -> bool: ...


Categoricals are indeed comparable, so we need to keep

cmp0xff · 2025-12-22T12:34:01Z

pandas-stubs/core/arrays/datetimelike.pyi

-    def min(self, *, axis=..., skipna: bool = ..., **kwargs: Any): ...
-    def max(self, *, axis=..., skipna: bool = ..., **kwargs: Any): ...
-    def mean(self, *, skipna: bool = ...): ...


Maybe keeping them is better

cmp0xff · 2025-12-22T12:34:51Z

pandas-stubs/core/arrays/datetimes.pyi

-    def __init__(self, values, dtype=..., freq=..., copy: bool = ...) -> None: ...
+    def __init__(
+        self,
+        values: Series | Index | DatetimeArray | npt.NDArray[np.object_],


cmp0xff · 2025-12-22T12:36:33Z

pandas-stubs/core/arrays/datetimes.pyi

+    def day_name(self, locale: str | None = None) -> Series | Index: ...
    @property
-    def time(self): ...
+    def time(self) -> npt.NDArray[np.object_]: ...


Suggested change

def time(self) -> npt.NDArray[np.object_]: ...

def time(self) -> np_1darray_object: ...

cmp0xff · 2025-12-22T12:36:49Z

pandas-stubs/core/arrays/datetimes.pyi

+    def time(self) -> npt.NDArray[np.object_]: ...
    @property
-    def timetz(self): ...
+    def timetz(self) -> npt.NDArray[np.object_]: ...


Suggested change

def timetz(self) -> npt.NDArray[np.object_]: ...

def timetz(self) -> np_1darray_object: ...

cmp0xff · 2025-12-22T12:37:05Z

pandas-stubs/core/arrays/datetimes.pyi

+    def timetz(self) -> npt.NDArray[np.object_]: ...
    @property
-    def date(self): ...
+    def date(self) -> npt.NDArray[np.object_]: ...


Suggested change

def date(self) -> npt.NDArray[np.object_]: ...

def date(self) -> np_1darray_object: ...

loicdiridollou · 2025-12-23T15:33:20Z

I may have put a little too much in this PR, will split so we can be more focused and not spread ourselves.

loicdiridollou and others added 5 commits December 15, 2025 12:30

GH1317 Add more defaults

3028115

GH1317 Add more defaults

77ddea8

GH1317 Add more defaults

6d78fd5

Apply suggestions from code review

95812e1

Co-authored-by: Yi-Fan Wang <cmp0xff@users.noreply.github.com>

Drop ANN exceptions from *arrays* and core/base.py

0d592ce

loicdiridollou marked this pull request as draft December 18, 2025 19:09

loicdiridollou added 2 commits December 18, 2025 14:10

Merge branch 'main' into gh1318_defaults_p2

3db3e22

Fix issues

51d4e03

loicdiridollou marked this pull request as ready for review December 18, 2025 19:16

loicdiridollou added 4 commits December 18, 2025 14:20

Fix issues

c9e5a3e

Fix issues

ef42649

Fix issues

7c7c9cc

Fix issues

ac0a84c

loicdiridollou requested a review from cmp0xff December 18, 2025 19:48

cmp0xff reviewed Dec 18, 2025

View reviewed changes

loicdiridollou added 2 commits December 19, 2025 11:32

Merge branch 'main' of github.com:loicdiridollou/pandas-stubs into gh…

2526813

…1318_defaults_p2

GH1318 PR Feedback

33740e3

cmp0xff reviewed Dec 19, 2025

View reviewed changes

GH1317 PR Feedback

6b116b3

loicdiridollou requested a review from cmp0xff December 19, 2025 20:20

MarcoGorelli reviewed Dec 22, 2025

View reviewed changes

cmp0xff requested changes Dec 22, 2025

View reviewed changes

loicdiridollou marked this pull request as draft December 23, 2025 15:33

loicdiridollou mentioned this pull request Dec 23, 2025

Drop ANN ignores from certain files in arrays #1583

Merged

3 tasks

	values: Series[PeriodDtype] \| npt.NDArray[np.integer] \| PeriodIndex,
	values: np_ndarray_anyint \| PeriodArray \| PeriodIndex \| Series[Period],

		def any(self, , skipna: bool = ..., *kwargs: Any): ...
		def all(self, , skipna: bool = ..., *kwargs: Any): ...

	values: Series \| Index \| DatetimeArray \| npt.NDArray[np.object_],
	values: Series \| Index \| DatetimeArray \| np_ndarray_str,

	def time(self) -> npt.NDArray[np.object_]: ...
	def time(self) -> np_1darray_object: ...

	def timetz(self) -> npt.NDArray[np.object_]: ...
	def timetz(self) -> np_1darray_object: ...

	def date(self) -> npt.NDArray[np.object_]: ...
	def date(self) -> np_1darray_object: ...

Uh oh!

Drop ANN exceptions from *arrays* and core/base.py #1568

Are you sure you want to change the base?

Drop ANN exceptions from *arrays* and core/base.py #1568

Conversation

loicdiridollou commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cmp0xff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarcoGorelli commented Dec 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarcoGorelli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Drop ANN exceptions from arrays and core/base.py #1568

Drop ANN exceptions from arrays and core/base.py #1568

loicdiridollou commented Dec 18, 2025 •

edited

Loading